NAME¶

ipsec_spi - manage IPSEC Security Associations

SYNOPSIS¶

Note: In the following,

<SA> means: --af (inet | inet6) --edst daddr --spi spi --proto proto OR --said said,
<life> means: --life (soft | hard) allocations | bytes | addtime | usetime | packets | [value...] <SA> --src src --ah (hmac-md5-96 | hmac-sha1-96) [--replay_window replayw] [<life>] --authkey akey
ipsec spi <SA> --src src --esp (3des | 3des-md5-96 | 3des-sha1-96) [--replay_window replayw] [<life>] --enckey ekey
ipsec spi <SA> --src src --esp [--replay_window replayw] [<life>] --enckey ekey --authkey akey
ipsec spi <SA> --src src --comp deflate
ipsec spi <SA> --ip4 --src encap-src --dst encap-dst
ipsec spi <SA> --ip6 --src encap-src --dst encap-dst
ipsec spi <SA> --del
ipsec spi --help
ipsec spi --version
ipsec spi --clear

DESCRIPTION¶

Spi creates and deletes IPSEC Security Associations. A Security Association (SA) is a transform through which packet contents are to be processed before being forwarded. A transform can be an IPv4-in-IPv4 or an IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication with no encryption), or an IPSEC Encapsulation Security Payload (encryption, possibly including authentication).

When a packet is passed from a higher networking layer through an IPSEC virtual interface, a search in the extended routing table (see ipsec_eroute(8)) yields an effective destination address, a Security Parameters Index (SPI) and a IP protocol number. When an IPSEC packet arrives from the network, its ostensible destination, an SPI and an IP protocol specified by its outermost IPSEC header are used. The destination/SPI/protocol combination is used to select a relevant SA. (See ipsec_spigrp(8) for discussion of how multiple transforms are combined.)

The af, daddr, spi and proto arguments specify the SA to be created or deleted. af is the address family (inet for IPv4, inet6 for IPv6). Daddr is a destination address in dotted-decimal notation for IPv4 or in a coloned hex notation for IPv6. Spi is a number, preceded by '0x' for hexadecimal, between 0x100 and 0xffffffff; values from 0x0 to 0xff are reserved. Proto is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. The protocol must agree with the algorithm selected.

Alternatively, the said argument can also specify an SA to be created or deleted. Said combines the three parameters above, such as: "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the address family is specified by "." for IPv4 and ":" for IPv6. The address family indicators substitute the "0x" for hexadecimal.

The source address, src, must also be provided for the inbound policy check to function. The source address does not need to be included if inbound policy checking has been disabled.

Keys vectors must be entered as hexadecimal or base64 numbers. They should be cryptographically strong random numbers.

All hexadecimal numbers are entered as strings of hexadecimal digits (0-9 and a-f), without spaces, preceded by '0x', where each hexadecimal digit represents 4 bits. All base64 numbers are entered as strings of base64 digits (0-9, A-Z, a-z, '+' and '/'), without spaces, preceded by '0s', where each hexadecimal digit represents 6 bits and '=' is used for padding.

The deletion of an SA that has been grouped will result in the entire chain being deleted.

The form with no additional arguments lists the contents of /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in ipsec_spi(5).

The lifetime severity of soft sets a limit when the key management daemons are asked to rekey the SA. The lifetime severity of hard sets a limit when the SA must expire. The lifetime type allocations tells the system when to expire the SA because it is being shared by too many eroutes (not currently used). The lifetime type of bytes tells the system to expire the SA after a certain number of bytes have been processed with that SA. The lifetime type of addtime tells the system to expire the SA a certain number of seconds after the SA was installed. The lifetime type of usetime tells the system to expire the SA a certain number of seconds after that SA has processed its first packet. The lifetime type of packets tells the system to expire the SA after a certain number of packets have been processed with that SA.

OPTIONS¶

--af

--edst

--spi

--proto

--said

--ah

hmac-md5-96

hmac-sha1-96

--esp

3des

3des-md5-96

3des-sha1-96

--replay_window replayw

--life life_param[,life_param]

--comp

deflate

--ip4

--ip6

--src

--dst

--del

--clear

--help

--version

EXAMPLES¶

To keep line lengths down and reduce clutter, some of the long keys in these examples have been abbreviated by replacing part of their text with ``...''. Keys used when the programs are actually run must, of course, be the full length required for the particular algorithm.

ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \ --src gw1 \ --esp 3des-md5-96 \   --enckey 0x6630...97ce \ --authkey 0x9941...71df

sets up an SA from gw1 to gw2 with an SPI of 0x125 and protocol ESP (50) using 3DES encryption with integral MD5-96 authentication transform, using an encryption key of 0x6630...97ce and an authentication key of 0x9941...71df (see note above about abbreviated keys).

ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \ --src 3049:9::9000:3101 \ --ah hmac-md5-96 \   --authkey 0x1234...2eda \

sets up an SA from 3049:9::9000:3101 to 3049:9::9000:3100 with an SPI of 0x150 and protocol AH (50) using MD5-96 authentication transform, using an authentication key of 0x1234...2eda (see note above about abbreviated keys).

ipsec spi --said tun.987@192.168.100.100 --del

deletes an SA to 192.168.100.100 with an SPI of 0x987 and protocol IPv4-in-IPv4 (4).

ipsec spi --said tun:500@3049:9::1000:1 --del

deletes an SA to 3049:9::1000:1 with an SPI of 0x500 and protocol IPv6-in-IPv6 (4).

FILES¶

/proc/net/ipsec_spi, /usr/local/bin/ipsec

SEE ALSO¶

ipsec(8), ipsec_tncfg(8), ipsec_eroute(8), ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)

HISTORY¶

Written for the Linux FreeS/WAN project <http://www.freeswan.org/> by Richard Guy Briggs.

BUGS¶

The syntax is messy and the transform naming needs work.

AUTHOR¶

Paul Wouters